/*
 * Copyright (C) 2011 by Fabien Barbero
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
package com.flickr.api.photos;

import com.flickr.api.FlickrServiceException;
import com.flickr.api.Paginated;
import com.flickr.api.people.User;
import java.util.List;

/**
 *
 * @author Fabien Barbero
 */
public interface PhotosService {
    
    /**
     * Add tags to a photo.
     * @param photo                     The photo.
     * @param tags                      The tags to add.
     * @throws FlickrServiceException   Error adding tags.
     */
    void addTags(Photo photo, String... tags) throws FlickrServiceException;
    
    /**
     * Remove a tag from a photo.
     * @param photo                     The photo.
     * @param tag                       The tag to remove.
     * @throws FlickrServiceException   Error removing the tag.
     */
    void removeTag(Photo photo, PhotoTag tag) throws FlickrServiceException;
    
    /**
     * Delete a photo from flickr.
     * @param photo                     The photo to delete.
     * @throws FlickrServiceException   Error deleting photo.
     */
    void delete(Photo photo) throws FlickrServiceException;
    
    /**
     * Fetch a list of recent photos from the calling users' contacts.
     * @return                          The photos of the contacts.
     * @throws FlickrServiceException   Error getting the photos.
     */
    List<Photo> getContactsPhotos() throws FlickrServiceException;
    
    /**
     * Fetch a list of recent photos from the calling users' contacts.
     * @param count                     Number of photos to return. This is only used if single_photo is not passed.
     * @param justFriends               Only show photos from friends and family (excluding regular contacts).
     * @param singlePhoto               Only fetch one photo (the latest) per contact, instead of all photos in chronological order.
     * @param includeSelf               Include photos from the calling user.
     * @return                          The photos of the contacts.
     * @throws FlickrServiceException   Error getting the photos.
     */
    List<Photo> getContactsPhotos(int count, boolean justFriends, boolean singlePhoto, boolean includeSelf) throws FlickrServiceException;
    
    /**
     * Fetch a list of recent public photos from a users' contacts.
     * @param user                      The user.
     * @return                          The photos of the contacts
     * @throws FlickrServiceException   Error getting the photos.
     */
    List<Photo> getContactsPublicPhotos(User user) throws FlickrServiceException;
    
    /**
     * Fetch a list of recent public photos from a users' contacts.
     * @param user                      The user.
     * @param count                     Number of photos to return. This is only used if single_photo is not passed.
     * @param justFriends               Only show photos from friends and family (excluding regular contacts).
     * @param singlePhoto               Only fetch one photo (the latest) per contact, instead of all photos in chronological order.
     * @param includeSelf               Include photos from the calling user.
     * @return                          The photos of the contacts.
     * @throws FlickrServiceException   Error getting the photos.
     */
    List<Photo> getContactsPublicPhotos(User user, int count, boolean justFriends, boolean singlePhoto, boolean includeSelf) throws FlickrServiceException;
    
    /**
     * Returns next and previous photos for a photo in a photostream.
     * @param photo                     The photo.
     * @return                          The context of the photo.
     * @throws FlickrServiceException   Error getting the context.
     */
    PhotoContext getContext(Photo photo) throws FlickrServiceException;
    
    /**
     * Retrieves a list of EXIF/TIFF/GPS tags for a given photo. 
     * @param photo                     The photo.
     * @return                          The list of exif informations.
     * @throws FlickrServiceException   Error getting exif.
     */
    List<Exif> getExif(Photo photo) throws FlickrServiceException;
    
    /**
     * Returns the list of people who have favorited a given photo.
     * @param photo                     The photo.
     * @return                          The persons who have favorited a given photo
     * @throws FlickrServiceException   Error getting favorites.
     */
    List<Person> getFavorites(Photo photo) throws FlickrServiceException;
    
    /**
     * Get information about a photo.
     * @param photo                     The photo.   
     * @return                          The informations of the photo.
     * @throws FlickrServiceException   Error getting the informations.
     */
    PhotoInfos getInfos(Photo photo) throws FlickrServiceException;
    
    /**
     * Returns a list of user's photos that are not part of any sets.
     * @param perPage                   The number of photos per page.
     * @param page                      The index of the page to return.
     * @return                          The list of photos.
     * @throws FlickrServiceException   Error getting the photos.
     */
    Paginated<Photo> getNotInSet(int perPage, int page) throws FlickrServiceException;
    
    /**
     * Get permissions for a photo.
     * @param photo                     The photo.
     * @return                          The permission of the photo.
     * @throws FlickrServiceException   Error getting permission.
     */
    PhotoAccess getPermission(Photo photo) throws FlickrServiceException;
    
    /**
     * Returns a list of the latest public photos uploaded to flickr.
     * @param perPage                   The number of photos per page.
     * @param page                      The index of the page to return.
     * @return                          The list of photos.
     * @throws FlickrServiceException   Error getting recent photos.
     */
    Paginated<Photo> getRecent(int perPage, int page) throws FlickrServiceException;
    
    /**
     * Returns the available sizes for a photo.
     * @param photo                     The photo.
     * @return                          The sizes of the photo.
     * @throws FlickrServiceException   Error getting the sizes of the photo.
     */
    List<PhotoSize> getSizes(Photo photo) throws FlickrServiceException;
    
    /**
     * Return a list of your photos that have been recently created or which have been recently modified.
     * Recently modified may mean that the photo's metadata (title, description, tags) may have been
     * changed or a comment has been added (or just modified somehow :-)
     * @param perPage                   The number of photos per page.
     * @param page                      The index of the page to return.
     * @return                          The list of photos.
     * @throws FlickrServiceException   Error getting photos.
     */
    Paginated<Photo> getRecentlyUpdated(int perPage, int page) throws FlickrServiceException;
    
    /**
     * Set the meta information for a photo.
     * @param photo                     The photo.
     * @param title                     The title of the photo.
     * @param description               The description of the photo.
     * @throws FlickrServiceException   Error setting the meta information.
     */
    void setMeta(Photo photo, String title, String description) throws FlickrServiceException;
    
    /**
     * Set permissions for a photo.
     * @param photo                     The photo.
     * @param ispublic                  If the photo is public.
     * @param isfriend                  If the photo visible to friends.
     * @param isfamily                  If the photo visible to family.
     * @param commentPerm               The comment permission.
     * @param addMetaPerm               The meta information permission.
     * @throws FlickrServiceException   Error setting permissions.
     */
    void setPerms(Photo photo, boolean ispublic, boolean isfriend, boolean isfamily, CommentPermission commentPerm, AddMetaPermission addMetaPerm) throws FlickrServiceException;
    
    /**
     * Set the tags for a photo.
     * @param photo                     The photo.
     * @param tags                      The tags.
     * @throws FlickrServiceException   Error setting the tags.
     */
    void setTags(Photo photo, String... tags) throws FlickrServiceException;
    
    /**
     * Set the safety level of a photo.
     * @param photo                     The photo.
     * @param level                     The safety level.
     * @param hidden                    true to hide the photo.
     * @throws FlickrServiceException   Error changing the safety level.
     */
    void setSafetyLevel(Photo photo, PhotoSafetyLevel level, boolean hidden) throws FlickrServiceException;
    
}
